
cassio 0.2.1 - Public Domain software by B. Watson
--------------------------------------------------


Introduction
------------

cassio is a tool for working with Atari 8-bit cassette (.cas) files on
Linux or other UNIX-like systems.

With an SIO2PC cable, cassio can emulate an Atari 410/1010 cassette
drive, allowing you to load cassette images on a real Atari, from your
Linux system.

Without an SIO2PC, cassio is still useful for converting, analyzing,
and repairing .cas image files.

Also included are Linux versions of Ernest R. Schreurs' original WAV2CAS
and CAS2WAV and Gienek's XEX2CAS and CAS2CAS, ported from MS-DOS.


Installation
------------

See the file INSTALL.txt for instructions on compiling/installing.


Quickstart
----------

There's quite a lot of documentation included with cassio, but most
people want to run new software without spending hours reading about it
first. If this describes you, bear with me for long enough to read this
quickstart section before you dive right in...

I assume you've got an Atari 8-bit computer and an SIO2PC cable connecting
it to the first serial port (/dev/ttyS0) of your Linux box, and that
you've already tested it (e.g. it works with sio2linux). I also assume
you have a cassette image to try out (if you don't, go download one from
somewhere like www.atarimania.com).

To boot a cassette image on your Atari, turn on the Atari, hold down Start
(and Option, if needed). After you hear the cassette tone from the Atari,
press Enter on the Atari. On the Linux box, run:

   cassio filename.cas

(If your SIO2PC is on the second serial port, add a "1" to the end of
the command: "cassio filename.cas 1")

You should be pressing Enter on the Atari BEFORE pressing Enter on the
cassio command, or at least press Enter on both keyboards at the same
time.

If cassio gives you an error message and exits, see "Troubleshooting"
below. Otherwise, cassio will start sending cassette data to the Atari.

After 10-20 seconds, you should hear the Atari's usual SIO noises as it
loads the cassette image. Congratulations, you've turned your highly
advanced and modern $3000 uber-fast server into an obsolete tape deck
from 1981 :)

Depending on the size of the cassette image, it could take up to 20-30
minutes to load (flashback to the olden days). Just be patient...

After the tape tones stop, the Atari should start running the software
it just loaded. If it does, you're in good shape. If it doesn't load
(Atari locks up or gives error message), see "Troubleshooting", below.

If everything works, and you have KDE installed, you can try the GUI.
It's called "kcassio", and can be run from a shell or from a KDE launcher.
It's not really a very good GUI (sorry about that!), but it does let
you load tapes on your Atari without using the keyboard.

Now, read on to learn the rest of the story...



Capabilities
------------

The main purpose of cassio is to emulate an Atari 410/1010 tape drive,
to allow you to load cassette images. Think of it as sio2linux or AtariSIO
for cassettes instead of disks.

As it loads the tape image, cassio analyzes the file and prints out a lot
of useful information. Even if you don't have an SIO2PC, you can use this
information to:

- Find out whether a .cas file is a BASIC program or something else

- Dump the data in the .cas image file to another file, which will contain
  only the data that the Atari would see (then you can disassemble the
  code in the file, etc). Also, cassio will tell you the load and init
  addresses, for a boot tape.

- Detect various types of errors in .cas files, that would keep them from
  running on a real and/or emulated Atari, including timing errors,
  short blocks, and blocks with bad checksums. There are also options
  to cassio that can help you work around timing errors, or permanently
  fix them.

- Find out how many files are on a data tape image (or how many boot stages
  are on a bootable tape image).

- Change the timing, baud rate (within limits), and description field
  of a .cas image. You can create a faster-loading version of your
  favorite game image, and (if you have an SIO2PC or a tape deck and
  drive) load it into your Atari. (You can also create images that won't
  work at all, if you're not careful!)

- Create .cas images from files on your filesystem, or extract the file
  contents of a .cas image to your filesystem.

If you have a real Atari and an SIO2PC cable (but no real tape drive
or tapes):

- Use your PC to emulate the Atari tape drive, so you can load cassette
  based software on the real thing.

- Load tape software at faster speeds than a real tape drive (currently,
  up to 1.5x the standard speed).

- Write Atari code on your *NIX workstation, using a modern editor and
  a cross-assembler, create a boot tape image or BASIC ENTER-compatible
  tape image, and run the code on a real Atari.


If you have a real Atari and a real tape drive, but no SIO2PC cable,
you might also want to:

- Download a .cas image from the 'net; use cas2wav to turn it into an
  audio file; play the file through your sound card while recording it
  on an audio tape; use the tape in your 410/1010 to boot your Atari.

- Make a perfect digital copy of an Atari tape: play the tape on a regular
  tape deck while recording to a .wav file with your sound card; use
  wav2cas to convert the .wav file into a .cas file. You can then use
  the .cas file with cassio; share it with your Atari buddies; and/or
  use cas2wav to convert the .cas file back into a .wav, then record the
  .wav to a cassette. This can actually result in an Atari tape that's
  a *better* copy than the original.

- If you don't have an Atari disk drive, you can convert many Atari DOS
  binary files (aka XEX files) to cassette images, and load them on a
  real Atari with a tape drive, using the xex2cas and cas2wav utilities.

If you have some Atari tapes you'd like to use with an Atari emulator,
or on a real Atari (but you don't have a tape drive), you can also
convert them to .cas images using wav2cas and a standard audio tape deck.


Usage
-----

There are a LOT of options, and (for now anyway) they're all single letters
with no GNU-style --long-option support.

You can run "cassio -h" for help (or "cassio -h|more" for easier reading).
The file "README_help.txt" is a copy of the help, if you'd prefer to
read it that way. Also, once cassio is installed, you can read the same
information via "man cassio".

You can also run "cassio -?" for a short usage message.

Also, see "README_examples.txt" for real-world examples, and the FAQ
in this document for further explanations.


Troubleshooting
---------------

Note to AtariSIO users: You have two choices for running cassio and
AtariSIO on the same system.

  1. Apply the atarisio-070415-tapesupport.diff patch to a copy of
     AtariSIO 070415, compile and install the patched AtariSIO, then
     compile cassio with AtariSIO support (see INSTALL.txt and
     README_atarisio.txt for more detail). As an added benefit, the
     patched version of AtariSIO can be used to load .cas images the
     same way cassio can (though without "fast load" or any of cassio's
     image analysis functions).

  2. Compile cassio without AtariSIO support. To run AtariSIO, make sure
     its kernel module is loaded ("modpobe atarisio port=/dev/ttyS0").
     To run cassio, exit from atariserver first, then "rmmod atarisio"
     before starting cassio.

Note to sio2linux users: Make sure you're not trying to run sio2linux
and cassio at the same time on the same serial port. If you do, you and
your Atari will both get very confused...


Common problems and solutions:

Symptom #1:
cassio gives me a "/dev/ttyS0: Permission Denied" error

Problem:
Your user account doesn't have permission to use the serial port

Solutions:
One of (a,b,c):
(a) Change the permissions on the serial port: "chmod 666 /dev/ttyS0"
    This will allow any user on your box to access the serial port.
    If the /dev/ttyS* permissions keep changing back, you may need to
    edit your udev or devfs configuration to make the change permanent.
(b) some systems have a "tty" group that owns the TTY devices; add your
    user to this group
(c) run cassio as root (NOT RECOMMENDED), or as setgid to the group
    that owns the serial ports. Setgid example:
    chgrp tty /usr/local/bin/cassio
    chmod g+s /usr/local/bin/cassio


Symptom #2:
cassio gives me a "/dev/ttyS0: No such file or directory" error
(or possibly a "Input/output error")

Problem:
(a) You don't have any serial ports...
(b) You're trying to use the wrong (non-existent) port,
(c) Your kernel doesn't have a driver for the serial port

Solutions:
(a) Use a different computer or buy an add-on PCI serial port card
    (make sure it contains a real 16550A UART!)
(b) Figure out which port has the SIO2PC cable, specify that port.
    Example: cassio file.cas /dev/ttyS1
    (if this works, you can recompile cassio with DEFAULT_TTY_DEV=/dev/ttyS1)
    If you're new to using serial ports on Linux, it's worth mentioning
    that the numbers are one less than they would be in DOS/Windows:
    COM1: is /dev/ttyS0, COM2: is /dev/ttyS1, etc.
(c) Try something like "modprobe serial", or recompile the kernel


Symptom #3:
cassio doesn't give me any errors, but the Atari can't load the file
(freezes, or displays garbage)

Problem:
(a) There's something wrong with your .cas file
(b) The .cas file is fine, but it's not compatible with your Atari
    (e.g. XL-only software won't run on an 800).
(c) You're trying to boot a BASIC program, or trying to CLOAD a boot
    tape.
(d) You're trying to use the wrong serial port
(e) There's something wrong with your SIO2PC, serial cable, or SIO cable
(f) There's something wrong with your Atari

Solutions:
(a) Try a different .cas file
(b) Some programs only work on the 400/800, some only work on XL/XE,
    some need 48K or 64K of RAM, some only work on PAL (European)
    hardware, some only work on NTSC (US) hardware... there are
    workarounds (Translator disk, OS upgrade/replacement mod), but
    that's really not something I can fix for you :(
(c) Load boot tapes by booting the Atari while holding down Start (and
    Option, for XL machines). Load BASIC tapes by booting with BASIC
    enabled, then use CLOAD or LOAD "C:".
    cassio tries to guess the file type and gives a brief description,
    but sometimes it might guess wrong...
(d) Use the correct serial port
(e) Test your hardware with sio2linux or AtariSIO
(f) same as (d), also test your Atari with a real tape and drive

Note: Often you can diagnose the problem by listening to the sound
coming out of the Atari. If you never hear anything, the Atari's not
receiving the data at all. If you hear normal "beeep, beeep" noises for
a while, then it switches to "farrrt, farrt" or a series of "blips",
that means the Atari is able to receive data, but at some point it lost
sync (which means at least your Atari and SIO2PC are talking to each
other). Keep in mind that some boot tapes (commercial games especially)
will disable the SIO loading noises part of the way through the boot,
though you should *always* hear at least the first 2-3 blocks.


Symptom #4:
I have a .cas image that works in an emulator (such as Atari800Win),
but not with cassio on a real Atari.

Problem:
(a) (see Problem #3b)
(b) The PRWT timing in the .cas file is bad.
(c) The game/program is trying to pause the tape (via the motor control line).

Solutions:

(b) Try to override the image's timing with pause/rewind and/or some
    combinations of the -d -p -s -l flags. Helps to know what you're
    doing here.

    Also, try turning off "Fast SIO" or "SIO Patch" support in the
    emulator. If it starts having the same problem as the real Atari,
    it means whoever made this .cas image never bothered to test it on
    a real Atari, only on an emulator... though there's a good chance
    you can get it to work on your real Atari by overriding the timing.

    Note: I've been informed that Atari800Win Plus 4.0 required the SIO
    patch to be on, for cassette images to load at all. Not sure whether
    this applies to earlier versions.

(c) Remember, there's no motor control support in the SIO2PC. If you
    notice cassio sending blocks, but the Atari isn't making its normal
    tape-loading tones, try rewinding cassio to the first block after
    the tones stopped (this block should have a PRWT above 10 seconds)
    and letting it play from there.
    Unfortunately, some games disable the SIO tape-loading tones, so this
    method isn't foolproof.


Symptom #5:
I have a .cas image that doesn't work, and cassio keeps giving me warnings
about bad block lengths, baud-correction bytes, and/or checksums.

Problems:

(a) The image is bad, because it was either created from a bad tape,
or recorded with lots of noise. Either way, wav2cas couldn't get all
the data from the .wav file.

(b) The image uses a custom loader, which does strange things with the
POKEY chip (things that aren't supported by the .cas file format).

(c) The image uses a custom loader, and would work correctly, but it's
having motor-control issues.

Solutions:

(a) Re-record the wav file, try a different copy of the cassette (often
the back side of a game tape contains a second copy of the game), make
sure the tape doesn't have an audio track (or if it does, make sure you
only record the data track (right stereo channel)). It's also possible to
apply a bandpass filter or hand-edit the .wav file to fix bad recordings
sometimes. If you've made several recordings, but wav2cas gives you
bad blocks in all of them, it may be possible to use cas2cas to piece
together a working image using good blocks from 2 or 3 bad .cas images.

(b) Wait a while... When Kr0kti's "extended CAS" format is released,
cassio will be updated to support it, which will fix this problem.

(c) This is difficult to diagnose, but see Symtom #4, above.


More to be added, as it's discovered. If you have a problem not mentioned
here or in the FAQ, let me know.


PAQ (Possibly Asked Questions)
------------------------------

This is like a FAQ, except that nobody's had a chance to ask any questions
yet, so I wrote them all myself :)


Q: Where do I get .cas images?

A: Try www.atarimania.com or XL-Search. There's also an extensive archive
   (in Polish) at http://cas-archive.pigwa.net. You can also create .cas
   images from your Atari tape collection.


Q: I hate command line programs, is there a GUI?

A: Try "kcassio". It's not a very *good* GUI, but it'll at least let you
   load .cas images without having to do any typing... I plan to write
   a better one Real Soon Now... but I'm really a text-oriented kind of
   guy, so if anyone else wants to do a GUI frontend, I welcome it.


Q: I found a bug in cassio! How do I report it? (or...)
Q: I have an idea for a cool feature for the next version of cassio!
   How can I let you know about it?

A: You can send me an email: urchlay (at) urchlay (dot) com
   [replace the (at) and (dot) with the obvious...],
   or you can contact me on the forums at www.atariage.com,
   username Urchlay.

   If you're having trouble with a specific .cas file, you can attach
   it to the message: images are small, by today's standards, so it
   won't cause any problems. However, please don't try to send me a
   .wav file without asking first!


Q: I found a bug in cas2wav or wav2cas, how can I contact the author?

A: Please don't bother Mr. Schreurs with bug reports or questions about
   the Linux ports of cas2wav/wav2cas. Instead, get in touch with me
   (see previous answer).

   I haven't been able to test cas2wav or wav2cas with real hardware
   because I don't own a working Atari tape drive or any tapes. The
   .wav files produced by cas2wav sound OK to my ears, and wav2cas is
   able to convert them back into .cas files which load correctly with
   cassio and my 1200XL, but without a tape drive or any tapes, I
   can't guarantee they'll work for real. If they don't work for you,
   *please* let me know so I can fix them.

   Update 20070429: I've tested wav2cas with audio output from my Atari
   recorded during a CSAVE and processed with a bandpass filter; this
   works pretty well. Also, I've tested it with a couple of .wav files
   people have recorded and posted to AtariAge. It works the same as the
   DOS version, from what I can tell.

   However, wav2cas tends to crash (segfault) if you feed it something
   other than a .wav file recorded from the data track of an Atari tape.
   It really should exit gracefully if it can't process the file...

Q: I found a bug in cas2cas or xex2cas, how can I contact the author?

A: Please don't bother Mr. Gienek with bug reports or questions about
   the Linux ports of cas2cas/xex2cas. Instead, get in touch with me.


Q: What happened to CAS2SIO? Why didn't you port that instead of writing
   this silly cassio program?

A: Two reasons. One, CAS2SIO does direct I/O to the UART at the I/O
   port level, which is fine on a simple single-user system like MS-DOS,
   but not on Linux/UNIX (it would have to either run inside the kernel,
   or at least run with root privileges, neither of which is desirable).

   Two, I thought of so many features I wanted to add that it wouldn't
   have saved much time/effort to start with the existing CAS2SIO code.

   cassio does include a "cas2sio" shell script, for people who are
   familiar with CAS2SIO, but it's just a wrapper that translates the
   options and calls cassio to do the real work.


Q: Will cassio work with my SIO2PC? Where do I set the cable type?

A: Yes. You don't need to set the cable type: when you set the cable
   type AtariSIO or APE, you're telling your software which serial
   port pin is wired to the COMMAND pin on the SIO port. This is very
   important for emulating disk drives and printers, but... the cassette
   drive doesn't use the COMMAND pin at all. All SIO2PC interfaces use
   the same pins for data output, regardless of cable type.


Q: Can I use cassio with the new USB version of the SIO2PC?

A: Not yet. Steve Tucker is still developing the USB SIO2PC, and
   he's promised to provide 3rd-party support via libusb. When the
   libusb driver is complete, I'll have to add code to cassio to
   support it.

   The good news about the USB version is that, when it's finally
   supported, it should have full motor-control support (and possibly
   even audio-in from the Atari, which means cassio could be modified
   to allow saving data from the Atari to a .cas image).


Q: But my computer doesn't have any serial ports, only USB. How am I
   supposed to use cassio?

A: There's a very good chance that you can use a regular serial port
   SIO2PC device with a USB to RS-232 converter. Normally, this is
   a no-no for an SIO2PC cable (it won't work with AtariSIO, sio2linux,
   or APE), but cassio only uses the TX (transmit data) pin of the
   serial port, for one-way communication (disk drives and software that
   emulates them require 2-way communications, with direct control over
   the port, but the cassette drive is much simpler).

   In theory this should work, but I've just now tested it with an FTDI
   adaptor and it didn't work. I've had trouble with the FTDI for every
   other application I've tried to use it with, though. I'm not sure
   whether this is a hardware problem or a Linux kernel problem...


Q: Can I use cassio with an ATART interface instead of an SIO2PC?

A: Yes, but cassio doesn't support the extra cassette-related parts of
   the ATART interface yet. This means that it will treat the ATART as
   a plain SIO2PC: the motor control output won't work, nor will the
   audio input from the Atari (see next question).


Q: Is the AFMS board supported?

A: Not yet.


Q: Why don't you support the ATART/AFMS?

A: Because I don't have them... Make or buy me one, and I'll get right on
   it! Or, wait until I can afford to buy one on my own (writing free
   software is fun, but it doesn't bring in a lot of cash, you know...)


Q: What about Atari tapes that have an audio track? Does cassio work with
   those?

A: Not entirely. The .cas file format doesn't provide a way to include
   audio samples. You can still use the data track with cassio, and if
   you have a separate .wav or MP3 file of the audio, you can play it
   in an audio player while cassio is running. However, most tapes with
   audio tracks rely heavily on motor control (not supported by cassio
   or SIO2PC), so this will be a manual trial-and-error process.

   A future version of cassio may include audio-sample support in .cas
   files. This may or may not be a part of Kr0kti's extended CAS format.

   Note that, if you're converting a .wav file to a .cas image, you need
   to strip out the audio track (left channel) and feed wav2cas only the
   data (right) track. Also note that there's often crosstalk between
   the audio and data channels (unavoidable with cassette technology,
   sometimes made worse by recording with cheap sound cards), so wav2cas
   may have trouble processing the data track due to the presence of
   the audio track at low volume... A bandpass filter may or may not
   help here.


Q: I tried to SAVE (or CSAVE) a program, why didn't it work?

A: cassio is read-only, from the Atari's point of view: it only supports
   sending data to the Atari, not receiving it.

   This is a hardware limitation: When writing data to cassette, the
   Atari actually sends *audio* to the tape drive (not digital data [*]),
   but the SIO2PC cable doesn't connect the Atari's audio output line to
   the PC. You can connect your Atari's audio output to your sound card,
   and record to a .wav file that way. cassio doesn't support this yet,
   but wav2cas does.

   You can also try the -R option to (try to) read digital data from the
   tape drive, while it's playing back a tape. This may or may not work
   with your particular drive and tape...

   [*] However, the Atari expects to receive data (NOT audio) when
       *loading* a tape. The tape drive has a (very simple) A/D
       converter onboard, but no D/A converter (instead, the POKEY
       chip inside the Atari does D/A conversion).


Q: Why can't cassio detect when there's an error sending data to the
   Atari?

A: Because a real Atari tape drive can't do that either:
   the Atari cassette protocol has no handshaking or feedback at all. The
   Atari never talks back to the cassette drive (or cassio) to indicate
   success or failure (don't blame me, that's how the Atari OS and tape
   drive have worked since they were invented in the 1970s)

   Once you get used to the normal tape loading sounds that come out of
   the Atari, you can hear errors (they sound more like a fart or a series
   of blips than a regular beeeep), though a few games turn off the SIO
   noisy I/O and load in silence.


Q: What's all this about motor control? (or...)
Q: I have a game or program that I use on a real 410/1010 that stops
   the tape part of the way through the load, shows an intro/menu/something,
   then starts the tape back up. When I try to use it with cassio, it
   doesn't work. Why not?

A: A real 410/1010 tape drive has a motor control line (an actual wire in
   the cable) that the Atari can use to tell the tape drive to pause and
   start the tape. This is why the tape reels don't start spinning when
   you first try to load or CLOAD a tape (you have to press a key first).

   However, the SIO2PC cable doesn't connect the SIO motor control line
   to your PC serial port (it's not needed at all for disk emulation),
   so cassio can't read this signal from the Atari.

   Someone who knows hardware better than I do could design an SIO2PC or
   SIO2PC-like device that does connect the motor control line. When/if
   that happens, I'll have to add code to cassio to support it.

   Note: the ATART does NOT connect the Atari's motor control line to
   the PC serial port, when used in SIO2PC mode. Replacing your SIO2PC
   with an ATART will not help with loading tapes into the Atari.

   For now, all is not lost: If you know when the Atari wants to pause
   the tape, you can manually pause by pressing the space bar. It takes
   a bit of deduction to figure out when to do this, but a good guess is
   that, if the game starts displaying an intro or menu during the load,
   you should pause until you hear the "press play" tone again. The good
   news is that you have plenty of time: there should be a long PRWT
   delay on the next block (over 10,000 milliseconds) in situations like
   this. The Atari is expecting to see 10 to about 45 seconds of silence
   before the first block's data, after the "press play" tone, so if
   you're late hitting Pause, just wait a few extra seconds before
   unpausing.


Q: I'm trying to boot a BASIC program, why doesn't it work?

A: Remember, BASIC programs aren't bootable. Instead, you have to boot
   the BASIC cartridge or built-in BASIC, then CLOAD (or possibly
   LOAD "C:") the program, then RUN it.

   If the Atari locks up during the CLOAD/LOAD, it's possible that the
   program requires an extended BASIC, such as the BASIC XL cart, or
   Turbo BASIC XL. cassio can't detect this, currently.


Q: Can I use cassio with MAC65 / Music Composer / (whatever)?

A: Most languages and applications should work just fine. I don't know
   of any language/app that uses a weird tape format (doesn't mean they
   don't exist, though). If you're having trouble with a particular app,
   let me know, and I'll do what I can to help debug the problem.


Q: Is there a way to avoid the long pause at the beginning of the load,
   or the long pauses in a multi-stage boot tape?

A: Not entirely (due to the way the Atari OS ROM works), but you can
   make them a little shorter with the -l option. If you try to make them
   shorter than 9-10 seconds, though, you'll get load errors. This is a
   limitation of the Atari OS ROM.


Q: I hate waiting for tapes to load! Isn't there some way to make it
   go faster?

A: You can try the -f (fast mode) or -m (medium speed mode) with cassio.

   Fast mode gives a 1.5x speedup on average (a 15-minute tape will load
   in 10 minutes), but it only works with 75-80% of the images out there.
   However, fast mode *does* work with all BASIC CLOAD images.

   Medium mode is a little slower (about 1.3x normal speed), but it should
   work with almost any image that works at normal speed.

   At some point, I'll be working on a custom cassette handler for the
   Atari, which will be able to load tape images from cassio at a much
   higher speed (19200 baud is my goal). This will require the handler
   to be loaded into the Atari at normal speed, and may (depending on
   how things work out) only work on XL/XE machines.


Q: What's the meaning of all the junk in the status/progress report?

A: Observe...

Block   3: data, length   132, PRWT 18907ms       0.0%,  ETA 12:28   W
[ a.... ]  [b]   [ c....... ]  [ d....... ] [e]   [ f]   [ g..... ] [h]

   Fields are:

   a - Block number within the image file. Normally, block 1 is the
       "FUJI" block (identifies the file as a .cas image, and contains
       the description, if any), block 2 is a "baud" block that sets
       the baud rate, and the data blocks start at block 3.

   Note: It's possible, though highly unusual, for there to be more than
         one FUJI and/or baud block. If the first block of an image isn't
         a FUJI block, though, cassio refuses to process it (because it's
         probably some other kind of file). Also, an image that doesn't
         contain a baud block before the first data block is an invalid
         image (cassio is smart enough to process it anyway, but other
         software might not be; in that case, use "cassio -E" to fix the
         file).

   b - Block type: FUJI, baud, data, or unknown.

   c - length of data block, in bytes. This includes the checksum and
       header bytes. For standard tape files, this will always be 132
       bytes. Multi-stage boot tapes sometimes contain blocks of other
       sizes (to speed up loading and/or to make it harder for game
       crackers to read the data). On the other hand, if a file is all
       132-byte blocks except for one or two smaller blocks, it might
       be a bad image (made from a real tape that has physical damage
       to the media).

   d - PRWT (Pre-Write Record Time), in milliseconds. This represents
       the delay between the data blocks that you can hear when loading
       a tape. The PRWT delay for a block is the amount of delay *before*
       the data. All images should have a long (10 second or more) PRWT
       on the first data block, which represents the tape leader. If
       you have an image that doesn't, you can simulate it by adding
       "-d 10" to the cassio command line, or by simply waiting 10 seconds
       between starting the Atari load process and running cassio.

   e - This field is either blank, or contains "[F]".

       Blank means that the PRWT value shown is the one that's actually in
       the tape image file.

       [F] means that the PRWT has been altered (forced to be
       longer/shorter) by cassio. This only happens if you use one of
       the -f, -l, -s, -p, or -d options to cassio, or if the initial
       tape leader is shorter than 10 seconds.

   f - Percent complete. This starts at 0% and works its way towards 100%.
       The percentage is based on the amount of data that has been sent
       to the Atari, *not* the amount of time that has elapsed.

   g - Estimated time left until the process is done.

   h - During loading, this lets you know what's happening. It will either
       be a "spinner", a dot (period, "."), a "W", or a "P".

       The "spinner" appears during PRWT's longer than one second, and it
       exists just to let you know cassio is alive and well. Once the
       remaining PRWT time gets below one second, it will turn into a dot.

       The dot means that the playback is waiting for the PRWT time to
       expire, and that the remaining time is less than one second.

       When it changes to a W, that lets you know that cassio is writing
       the block's data to the serial port.

       The letter P means the playback is paused (by you pressing the
       space bar, or using the FF/rewind controls). When you un-pause,
       the P will turn back into a spinner, dot, or a W.

       Writing cannot be interrupted by keyboard controls. When the W
       is being displayed, you can press a key, but it won't be acted
       upon until the current write-block operation has completed,
       which can take a couple of seconds.


Q: I use AtariSIO for disk emulation. It's really annoying to have to
   load/unload the atarisio kernel module when switching between cassio
   and AtariSIO. Are you going to fix that in the next version?

A: It's fixed now; you can compile AtariSIO with cassette support, then
   compile cassio with AtariSIO support. See INSTALL.txt and
   README_atarisio.txt for more information.

   I'm hoping that Hias (author of AtariSIO) will accept my cassette
   patch and make it part of the official release of AtariSIO. If he
   does, future versions of AtariSIO won't need the patch.


Q: I have an image file that only works with special command-line options.
   Can I include this information in the image somehow, or store it in
   a config file somewhere, so I won't have to remember it next time?

A: Sort-of. You can use cassio's image editing mode to create a modified
   copy of the image (see next question).


Q: I have a bad image file that I want to try to fix. Is there a .cas
   image editor?

A: Yes (the -E option), though it's pretty limited so far. You can change
   the PRWT timing, baud rate, and description of a .cas image with
   cassio, but not (yet) the data in the image. To do that, you'll need
   to use a hex editor. Probably the easiest way to do this is to use the
   -o option to dump the file data (minus the framing/checksum bytes),
   use a hex editor, then recreate the .cas image with the -c option.


Q: I have some LISTed Atari BASIC (or assembler, etc) sources, or text
   files, that I'd like to load into the Atari. Is there a way to make
   a .cas image of these?

A: Yes. Use cassio's -c or -ec options (depending on whether the file
   has Atari or UN*X end-of-lines). For an ENTERable tape, also use
   -s4000 to use long IRGs. You can also use -c on a SAVEd Atari BASIC
   disk file to create a CLOADable .cas image (or use -o on a CLOAD
   image to create a LOADable disk file).

   For other application data files (besides BASIC), you usually need
   -s4000, for long IRGs. You can find out which IRG type your app uses
   by trying to save a file to the cassette (even if you don't have one),
   and listening to the pauses between the tape tones.


Q: I'm working on writing an Atari game with a cross assembler/compiler.
   How do I make a boot tape image?

A: Use cassio's -c (create image) mode. You can either include an Atari
   boot tape header at the start of your code, or write the game as a
   DOS binary load file, then use xex2cas to make a boot tape from that.
 
   If you want to create a multi-stage boot loader tape, you can do this
   too. Make each stage a separate object file. The first stage needs
   a boot header; the second stage can be whatever you want (since the
   first stage will load it). Convert each stage to a .cas image, then
   concatenate them (cat stage1.cas stage2.cas > boot.cas). The resulting
   image will have an extra FUJI and baud block at the beginning of the
   second stage, which won't hurt anything, and which you can remove with
   "cassio -UE".

   The first block of the first stage of a boot tape should look something
   like this (assembly code; DASM syntax; UNtested code):

; assemble with "dasm -f3"

   org boot_cont - 6
boot_block:   ; standard 6-byte Atari boot tape header
   .byte 0    ; unused, can be anything
   .byte [end_code-load_address]/128   ; number of blocks to load
   .word load_address                  ; just what it says...
   .word init_address                  ; zero, if no init routine

boot_cont:
; Boot continuation code goes here, if any
; ...

load_address:
; main chunk of code and data goes here
; ...

; At the end of your code:
  align 128 ; boot tapes are normally an even number of tape blocks
end_code


Q: I want to disassemble a boot tape to see how it works. How?

A: Use cassio's -o option to dump the code/data from the tape, then
   massage it into whatever format your disassembler requires.

   For multi-stage boot loaders, you can use the -X option to write
   each stage to a separate file, to make it easier to tell where the
   loader ends and the program data/code begins.


Q: Will wav2cas work with MP3 files instead of .wav files? (or...)
Q: Can I use my iPod to record Atari cassette audio and play it back?

A: wav2cas doesn't know how to read mp3 files, only wav files. That said,
   you can use an audio convertor (such as LAME) to turn an MP3 file
   into a .wav file. However, MP3 is a lossy format: the resulting wav
   file will not contain all the audio information that was originally
   used to create the MP3 file (if you have sensitive ears, you can
   actually hear the difference). I've only tested one MP3-to-wav
   conversion with wav2cas, and it didn't work at all.

   The iPod also uses lossy compression (similar to MP3 but different),
   so it has the same issue: it may or may not work, depending on what
   the compression strips out of the audio.

   If you really had a good reason to keep the audio files around, you
   could compress them with Flac or Shorten (lossless audio codecs),
   but once you've made a working .cas image of a tape, the audio file
   isn't all that useful any more...


Q: Audio CDs are lossless; can I store Atari cassette audio on those?

A: I don't know why it would be useful, but... Yes, absolutely.

   Remember, when loading, the Atari expects to receive data, not audio.
   An audio CD full of recorded Atari tape audio would only be useful for
   recording back to tape (for use with a real tape drive), or ripping
   to .wav files (for use with wav2cas/cassio). However...

   A neat hardware project would be a mini CD player built in to an Atari
   410 or 1010 housing. For bonus points, it should use a standard Atari
   9VAC/31VA power supply and use the motor control line to control the
   CD player's pause button. For double bonus points, use a CD recorder
   and support saving data on CD-R... for triple bonus points, make it
   act like a large disk drive, when a data CD is inserted.


Q: Is there another way to create a .cas image from a tape, besides recording
   a .wav file?

A: Yes, try cassio's -R option. This will allow you to play the tape in an
   Atari tape drive and (attempt to) read the serial data from your
   SIO2PC.  You'll need a way to turn on motor control for the tape drive:
   either a real Atari (POKE 54018,52), or a modified tape drive with
   a motor control enable switch. -R mode is very sensitive to motor
   speed variations, stretched tape, and dropouts, so it may not work
   with a particular tape or tape drive.


Q: What are xex2cas and cas2cas?

A: xex2cas is a utility by Gienek which will convert an Atari DOS binary
   load file (aka XEX file) into a bootable cassette image. May not work
   with all binary files.

   cas2cas is another utility by Gienek which attempts to piece together
   a working .cas image from parts of 3 broken ones made by sampling
   the same cassette 3 times.

   They are provided as-is. They were both originally written for MS-DOS,
   and should work exactly as the MS-DOS versions (I just made minor
   edits to get them to compile OK with g++).

   Please don't bother Mr. Gienek with bug reports or support requests
   for the Linux ports of xex2cas or cas2cas.


Q: What are the differences between cassio 0.1.0 and 0.2.1?

A: Four major new features:

   -R option, to read from a real tape drive with a SIO2PC
   -v option, to compare two .cas images and report the differences
      between them
   -X option, dumps data from each stage to a separate file
   -a option (autopause), helps with multi-stage games that require
      user interaction between stages

   Minor features:

   -i (info) mode now shows a warning for each bad block, but stops
      after 10 blocks.
   -i and -x together now show a hexdump of bad blocks only
   Serial ports can now be referred to as just a number (0, 1, etc)
     instead of having to type "/dev/ttyS1"
   -c and -o now support writing to standard output
   -M option, to force medium-length PRWT timing (works like -s and -l)
   -Q option, to suppress warnings
   -P, progress bar mode (looks similar to wget)
   -U, strips unknown blocks or extra FUJI/baud blocks in edit mode
   -z, normalize (same as -b600 -s260 -M4000 -l12000 -L)
   Enhancements to keyboard controls (rewind implemented)
   New status indicator during playback, shows whether cassio is
     sleeping, writing, or paused
   A few more warnings for various image problems
   Fixed a few minor bugs
   The cassio man page is now formatted correctly

   For all the gory details, see the Changelog


Q: What are the differences between cassio 0.2.1 and 0.2.2?

A: The main visible difference is that long options are now supported.

Instead of trying to remember that e.g. "-k" is for fast-forwarding to
a block, and that "-K" disables the keyboard, you can now refer to these
two options as "--ff-block" and "--disable-keyboard". They're longer to
type, but easier to remember (and you can still use the short options,
if you prefer). See README_help.txt or the man page for the new options.

The other differences are portability fixes that allow cassio to be run
on more platforms (even including MS Windows).


Other Documentation
-------------------

For your reading pleasure, here is a list of all the docs included with
cassio. Normally, they are installed in /usr/share/doc/cassio-$VERSION.

README.txt - you're reading it right now

README_help.txt - A copy of cassio's built-in help (-h option). This is
                  the same thing as the man page, minus the formatting.

README_atarisio.txt - how to get cassio to play nice with AtariSIO. Also,
                      how to get AtariSIO to support cassette images.

README_examples.txt - How to do common (and not-so-common) tasks with cassio

README_portability.txt - Reports from the field: how well does cassio work
                         on different peoples' setups?

README_windows.txt - Instructions for running cassio on MS Windows.

README_cas2wav.txt - Slightly modified copy of Ernest R. Schreurs'
                     docs for the original CAS2WAV for MS-DOS.

README_wav2cas.txt - Slightly modified copy of Ernest R. Schreurs'
                     docs for the original WAV2CAS for MS-DOS.

Mr. Schreurs has a deeper understanding of Atari tape mechanics than
I do, and explains them in great detail. These are worthwhile reading
even if you never plan to use wav2cas/cas2wav themselves.

README_xex2cas.txt - Slightly modified copy of Gienek's docs for the
                     original MS-DOS version of XEX2CAS.

README_cas2cas.txt - Slightly modified copy of Gienek's docs for the
                     original MS-DOS version of CAS2CAS.

Changelog - Look here to find out what's new in cassio.

INSTALL.txt - Install instructions

README_image_testing.txt - So far, I've tested cassio with about 50 tape
                           images. Here are the results, in excruciatingly
                           boring detail...

TODO - Bugs I plan to fix, or features I plan to add


Contact
----------------

You can reach me by email at: urchlay (at) urchlay (dot) com
[replace the (at) and (dot) with the obvious...]


Legalese
--------

The cassio source code and any executables built from it are Public Domain
software. Legally speaking, you may do anything you like with them: use,
copy, modify, redistribute for free or for profit, incorporate into your
own code...

However, as a courtesy, if you make any modifications to cassio to enhance
its functionality or fix bugs, I'd appreciate it if you sent me a patch,
or a copy of your fixed source code. You are not legally required to do
this, but it'd be the honorable thing to do. I'm only asking you, though,
not telling you to.

cassio, cas2wav, wav2cas, xex2cas, and cas2cas are provided as-is
without any warranty whatsoever. Neither I nor the original authors of
cas2wav/wav2cas/xex2cas are responsible for any damages caused to your
computer system that may result from the use of these programs. Please
do not contact the authors of cas2wav/wav2cas/xex2cas/cas2cas for support
of the Linux ports!

